@mnriem please review, we need to make this work with new Bob... Thankyou so much

As this fundamentally changes the layout for any Bob users what is the migration strategy? This will break them once they adopt a new version of Spec Kit so you need to make sure this goes through a deprecation cycle so they can migrate to the new Bob version. E.g make it an opt-in to the new version of Bob first and then in 2 minor releases (X.Y.Z where Y is minor) you can then remove the non-skill variant

Hi @mnriem
this should not break for Bob 1 user cause it was already compatible with skill mode.
Still needed this?

Thanks @davidebibm — but I think we're talking about two different layers, and this still needs to change before it can land.

Your point is about Bob the tool — that Bob 1.x can already read the skills layout. My concern is about Spec Kit's generated output: this PR changes what specify writes for the bob integration from .bob/commands/*.md to .bob/skills/speckit-<name>/SKILL.md. Any project someone already initialized has .bob/commands/*.md on disk. When they upgrade Spec Kit and re-init or switch, that layout is orphaned/replaced. That's a breaking change in our contract regardless of whether the Bob app happens to read both directories.

A hard cutover isn't acceptable here — we shouldn't catch existing users off guard. This needs to go through a proper deprecation cycle:

1. This release: make skills an opt-in and keep the existing .bob/commands markdown layout as the default. That's real dual-mode — setup() branching between the two layouts, the way Copilot does it — not the --skills flag as written now.
2. Next cycle: flip the default to skills, with the legacy layout still available.
3. Cycle after that: remove the legacy markdown mode.

As it stands the --skills flag is a no-op: BobIntegration is hardwired to SkillsIntegration and the MarkdownIntegration variant is deleted, so --skills=False still emits skills. There's no path that produces the old layout, so it doesn't actually provide the opt-in it implies.

Can you rework it along those lines — genuine dual-mode with skills opt-in first — so we phase this in without breaking anyone?

Ok, thankyou @mnriem i'll do that

@mnriem Done, hope this is what you are expecting

Please address Copilot feedback. You will need to update the description to reflect the reality

@mnriem Addressed Copilot comments and aligned with main

Please address Copilot feedback and resolve conflicts

@mnriem Solved Copilot fb and rebased to avoid get Copilot feedback on other devs code 👍

Addressed the three review comments in d929bfb. This push also merges current main into the branch (brings in #3544), so it's now up to date and self-consistent.

1. Bob legacy-install regression (bob/__init__.py) — the real bug. use/switch/upgrade on an existing Bob 1.x project (only .bob/commands/ on disk, no stored legacy_commands) hit is_skills_mode(None) → True and rewrote ai_skills: true, silently switching the project to the skills layout. is_skills_mode now accepts an optional project_root; Bob preserves an already-installed legacy layout until an explicit upgrade actually creates .bob/skills/. A fresh project still defaults to skills. Threaded project_root through the init and _update_init_options_for_integration call sites.

2. Copilot dual-mode separator (copilot/__init__.py) — Copilot inherited the mode-independent invoke_separator_for_mode default, returning its static ., so preset/extension command refs in a Copilot skills project rendered /speckit.<name>. Added an override that tracks the persisted ai_skills state (- skills, . default), consistent with build_command_invocation and effective_invoke_separator.

3. Bob extension-skill command-ref tokens — with main merged, the generic _resolve_command_ref_tokens from #3544 resolves Bob's __SPECKIT_COMMAND_*__ tokens via the CONDITIONAL_SLASH_AGENTS path (/speckit-<name>), so no Bob-specific build_command_invocation is needed. Added Bob to the command-ref-token regression parametrize plus dedicated Bob is_skills_mode/use-path tests to lock the behavior in.

Testing: full suite green on the merged result — 4524 passed, 5 skipped, 0 failures.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

Addressed review 4716253844 in 8a162b3.

Finding (valid): the legacy-layout detection wasn't applied when use/switch refreshes shared infrastructure. _set_default_integration() refreshed rendered shared templates via _with_integration_setting() / _invoke_separator_for_integration(), both of which resolved the invoke separator through effective_invoke_separator/is_skills_mode without project_root. For a pre-PR Bob 1.x project (.bob/commands/ on disk, no stored options) this defaulted to the skills - separator and rewrote rendered command refs to /speckit-* even though ai_skills stayed false.

Fix: threaded project_root through effective_invoke_separator, the two runtime helpers (with_integration_setting, invoke_separator_for_integration), and every call site, so Bob's on-disk legacy detection governs the separator before shared infra is refreshed. Added an end-to-end regression test (test_use_force_keeps_legacy_command_refs_in_shared_templates) that inits a legacy Bob project, runs integration use bob --force, and asserts rendered shared templates keep /speckit.* (dot) refs.

Full suite green: 4526 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

Addressed review 4716424313 in eeaf85f.

Finding (valid): register_commands runs once per detected agent, but the persisted ai_skills flag describes only the active integration (opts["ai"]). When another agent (e.g. Copilot) is active in skills mode while a legacy .bob/commands layout is also present, the code passed that global True to Bob's invoke_separator_for_mode, rewriting Bob 1.x command refs to /speckit-* instead of /speckit.*.

Fix: only consult the persisted flag for the agent it describes (opts["ai"] == agent_name); otherwise resolve the separator from that agent's own project-aware effective_invoke_separator(None, project_root). Added regression tests for the mismatched-active-agent case (legacy Bob refs stay /speckit.plan while Copilot is active in skills mode) plus a control for Bob-active skills mode.

Full suite green: 4528 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

Addressed review 4723246468 in 21922f8.

Comment 1 (is_skills_mode) — valid. The compatibility check treated the mere presence of a .bob/skills/ directory as proof the project is skills-based, so a legacy Spec Kit install (managed .bob/commands/speckit.*.md) that also carried unrelated Bob 2 skills was misclassified as skills — integration use bob then persisted ai_skills and rewrote shared refs. Now the Spec Kit layout is inferred from managed artifacts: legacy/command mode only when managed speckit.*.md command files exist and no managed speckit-* skill dirs do. A genuine skills project (managed speckit-* dirs) still resolves to skills; a fresh project still defaults to skills.

Comment 2 (agents.py registrar) — valid. For an inactive agent the separator used a disk-based effective_invoke_separator(None, project_root) fallback that could pick the skills - even though this registrar writes the static command layout (.bob/commands/*.md). Inactive agents now resolve the separator from the registrar's actual output layout (extension == "/SKILL.md"), so command-layout files keep /speckit.* refs regardless of sibling dirs; persisted ai_skills is consulted only for the active agent.

Updated the affected hook/E2E tests to use managed artifacts and added regression tests for the mixed-layout (is_skills_mode) and inactive-registrar scenarios.

Full suite green: 4531 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

Addressed review 4723782860 in 13db5f3.

Comment 1 (setup() drops project context on upgrade) — valid. setup() resolved the layout via is_skills_mode(parsed_options) without project_root, so integration upgrade bob on a Bob 1.x install (managed .bob/commands/speckit.*.md, no stored options) ignored the existing command files, generated skills, and stale-deleted the legacy commands — silently migrating despite the preservation contract. Now setup() passes project_root into is_skills_mode, so the same managed-artifact detection used by use also governs upgrades. Verified end-to-end: upgrade bob on a stripped legacy install keeps .bob/commands/ and creates no .bob/skills/.

Comment 2 (skill post-processing inconsistency) — valid. Only _BobSkillsHelper overrode post_process_skill_content to suppress the shared slash-command hook note; preset/extension skill generators call that hook on the registered BobIntegration, which inherited IntegrationBase's note-injecting default. Repeated the no-op (delegating to the skills helper) on the registered class so every Bob skill-generation path stays consistent with intent-activated core Bob skills.

Added regression tests for both (upgrade preservation + post-processing no-op). Full suite green: 4536 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

Addressed review 4724160183 and resolved the merge conflict with main. Pushed as ba6655c.

Comment 1 — no migration path from legacy → skills. Added an explicit --skills opt-in to the Bob integration. It forces the skills layout over on-disk auto-detection, so a legacy Bob 1.x install now has a supported migration: specify integration upgrade bob --integration-options="--skills" scaffolds .bob/skills/ and the upgrade's stale-file pass removes the old .bob/commands/*.md. --skills and --legacy-commands are mutually exclusive (clean error). Disk auto-detection is unchanged when neither flag is passed, so use/switch still won't silently migrate a legacy project.

Comment 2 — active-agent separator ignored the output layout. CommandRegistrar.register_commands now derives the command-ref separator from the output layout (agent_config["extension"]) for the active agent too, not the persisted ai_skills flag. A command-layout file (.bob/commands/*.md, .github/agents/*.agent.md) always renders /speckit.*; only a /SKILL.md scaffold uses /speckit-*. Bob and Copilot write their skills via their own setup()/skills path, so register_commands only ever emits their command-layout files — the stale-.bob/commands case now renders correctly.

Comment 3 — docs. Updated the Bob entry in docs/reference/integrations.md to document the skills-based default (.bob/skills/), the deprecated --legacy-commands opt-out, and the --skills migration path.

While validating the migration end-to-end I found a latent bug it surfaces: the upgrade Phase 2 stale-file cleanup built a throwaway manifest sharing the integration key and called uninstall(), which always deleted {key}.manifest.json. Any layout-shrinking upgrade (e.g. legacy → skills) wiped the freshly-saved manifest, leaving the project untracked and un-upgradeable. uninstall() now takes remove_manifest (default True); the stale-cleanup pass passes False.

Added regression tests for each of the above (opt-in, mutual exclusion, corrected active-agent separator, remove_manifest=False, and an end-to-end legacy → skills migration asserting the manifest survives and the project stays upgradeable). Full suite: 4555 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.